ZKIDROnline SDK

# ZKIDROnline SDK接口文档

## 前言

    ZKIDROnline通过http(s)协议监听24010(24011)端口，提供业界标准的Web Service API,供其他程序调用。
    ZKIDROnline具有如下特点：
        1.与浏览器无关
        2.提供标准的http get接口
        3.返回数据格式为json
        4.数据编码Utf-8

## 接口

### 返回数据格式

    {
        "ret":0,    //错误码，见附录
        "dev":1,
        "data":""   //数据
    }

### 获取基本信息

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/info
    OR
        https://127.0.0.1:24011/ZKIDROnline/info

> 接口返回

    {
        "ret":0,
        "data":
        {
            "server_version":"版本号(x.x.x)",
            "start":"服务启动时间(YY-MM-DD HH:MM:SS)",
            "now":"当前时间(YY-MM-DD HH:MM:SS)"
        }
    }

### 读取身份证信息

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=4&REPEAT=1&READTYPE=1
    OR
        https://127.0.0.1:24011/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=4&REPEAT=1&READTYPE=1

- REPEAT

  是否重复读卡(REPEAT=1表示重复读卡，其他放一次卡读一次)

- READTYPE

  读卡类型 = 1 读基本信息，形成文字信息文件WZ.TXT、相片文件XP.WLT、ZP.BMP，如果有指纹信息形成指纹信息文件FP.DAT

  读卡类型 = 2 只读文字信息，形成文字信息文件WZ.TXT和相片文件XP.WLT

  读卡类型 = 3 读最新住址信息，形成最新住址文件NEWADD.TXT

  其他值，则默认是读基本信息。

> 接口返回

    {
        "ret":0,
        "Certificate":
        {
            "Name": "", //姓名
            "Sex": "",  //性别
            "Nation": "",   //民族（二代证） or 国家（外国人用居证），港澳台通行证无此项
            "Birthday": "", //出生日期
            "Address": "",  //常住地址
            "IDNumber": "", //身份证号
            "IDIssued": "", //签发机关
            "IssuedData": "",   //签发日期
            "ValidDate": "",    //有效期截止日期
            "Other": "(null)",        //
            "CardNumber": "(null)",   //
            "PhotoName": "(null)",
            "Base64Photo": "base64照片",  //Base64照片
            "ImageName": "(null)",
            "Base64Image": "(null)",
            "fp_feature1":"Base64 String", //第一个登记手指指纹特征
            "fp_feature2":"Base64 String"  //第二个登记手指指纹特征
            "CardType": "",  //卡的类型 1二代证  2外国人居住证  3港澳台居住证
            "EnName": "", //英文名，仅外国人居住证才有
            "CnName": "", //中文名，仅外国人居住证才有
            "PassNum":"", //港澳台通行证号码
            "VisaTimes":""  //港澳台通行证签发次数
    }

### 设置语音播放

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=16&VoiceType=0
    OR
        https://127.0.0.1:24011/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=16&VoiceType=0
    备注：
    语音类型有(VoiceType的值)：
    0  请放卡
    1  读卡成功
    2  读卡失败，请重新放卡
    3  读卡成功，请核验指纹
    4  核验成功
    5  核验失败，请重按手指
    6  写卡成功
    7  写卡失败

> 接口返回

    {
        "ret": 0,
        "data":
        {
            "set":"successful"
        }
    }

### 读取SAM模块编号

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=11
    OR
        https://127.0.0.1:24011/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=11

> 接口返回

    {
        "ret": 0,
        "data":
        {
            "samid":"05.03-20131107-0001564594-1164073527"
        }
    }

### 获取身份证指纹

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=14
    OR
        https://127.0.0.1:24011/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=14

> 接口返回

    {
        "ret":0,
        "data":
        {
            "feature1":"Base64 String", //第一个登记手指指纹特征
            "feature2":"Base64 String"  //第二个登记手指指纹特征
        }
    }

### 采集指纹图像

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=1
    OR
        https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=1

> 接口返回

    {
        "ret":0,
        "data":
        {
            "rawBase64":"Base64 String",   //指纹图像原始图 Base64
            "jpgBase64":"Base64 String"    //指纹图像JPG Base64
        }
    }

### 采集指纹图像和模板

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=2
    OR
        https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=2

> 接口返回

    {
        "ret":0,
        "data":
        {
            "feature":"Base64 String", //指纹特征
            "rawBase64":"Base64 String",   //指纹图像原始图 Base64
            "jpgBase64":"Base64 String"    //指纹图像JPG Base64
        }
    }

### 指纹图像(原始图)比对模板

> 接口调用

    HTTP Post
        http://127.0.0.1:24010/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=3
    OR
        https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=3
    POST数据如下：
        {
            "rawBase64":"Base64 String",        //见rawBase64
            "feature":"Base64 String"           //指纹模板
        }

> 接口返回

    {
        "ret":0,
        "data":
        {
            "score": 80
        }
    }

### 指纹模板比对指纹模板

> 接口调用

    HTTP Post
        http://127.0.0.1:24010/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=4
    OR
        https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=4
    POST数据如下：
        {
            "regFeature":"Base64 String",           //指纹模板
            "verFeature":"Base64 String"           //指纹模板
        }

> 接口返回

    {
        "ret":0,
        "data":
        {
            "score": 80
        }
    }

### 获取要打开的端口号

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=5
    OR
        https://127.0.0.1:24011/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=5

> 接口返回

    {
        "ret":0,
        "dev":1,
        "data":{
                    "name":"COM5"
               }
    }

### 读IC卡物理卡号

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=1&iPort=5
    OR
        https://127.0.0.1:24011/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=1&iPort=5

> 接口返回

    {
        "ret":0,
        "dev":1,
        "data":
        {
            "ICSnr":"666005947"
        }
    }

> 备注：

    iPort//要打开的端口号

### 读身份证物理卡号

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=2&iPort=5
    OR
        https://127.0.0.1:24011/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=2&iPort=5

> 接口返回

    {
        "ret":0,
        "dev":1,
        "data":
        {
            "IDSnr":"10d5d000e508101b"
        }
    }

> 备注：

    iPort//要打开的端口号

### 获取IC卡数据

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=3&iPort=5&Sector=0&Idx=2&Key=FFFFFFFFFFFF
    OR
        https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=3&iPort=5&Sector=0&Idx=2&Key=FFFFFFFFFFFF

> 备注：

    iPort//要打开的端口号
    Sector//扇区号
    Idx//块索引
    Key//扇区密钥

> 接口返回

    {
        "ret":0,
        "dev":1,
        "data":
        {
            "ICdata":"*******"        //IC卡数据
            "ICid":666005947  //IC卡物理卡号
        }
    }

### 设置IC卡数据

> 接口调用

    HTTP Get
        http://127.0.0.1:24010/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=4&iPort=5&Sector=0&Idx=2&Key=FFFFFFFFFFFF&Data=*****
    OR
        https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=4&iPort=5&Sector=0&Idx=2&Key=FFFFFFFFFFFF&Data=*****

> 备注：

    iPort//要打开的端口号
    Sector//扇区号
    Idx//块索引
    Key//扇区密钥
    Data //写卡的数据(32个16进制字符)

> 接口返回

    {
        "ret":0,
        "dev":1,
        "data":
        {
            "ICid": 666005947
        }
    }

## 附录

### 附录1

错误代码 | 说明
--- | ---
0 | 成功
1 | 端口打开失败
2 | 数据传输超时
3 | 设置超时时间失败
4 | 设备忙打开失败
6 | 接口地址参数有误
10 | 没有找到卡
11 | 读卡失败
20 | 自检失败
30 | 其他错误
40 | 相片解码失败
100 | 超时
200 | 获取照片Base64失败
201 | 操作失败
202 | IC卡参数出错
-1 | 获取指纹失败
-100 | ID/IC卡模块加载失败
203 | 加载指纹采集库失败
204 | 加载指纹的算法库失败
205 | 初始化算库失败
206 | 初始化采集器失败
207 | 找不到二代证采集器
208 | 打开采集器失败
209 | 采集器采集图像失败
210 | 采集模板失败
211 | 比对模板无效
212 | 传入的JSON格式转换有误
213 | 比对失败
214 | 采集器采集图像超时
215 | 播报的语音类型不支持
216 | 设置播报语音失败
其他 | 未知错误